URL Security - PicketBox

Introduction

URL Security allows you to configure how your application's resources should be protected or not. It allows you to:

Protect resources using some security constraints like: AUTHENTICATION, AUTHORIZATION and NOT_PROTECTED
RBAC (Role Based Access Control)
Fine-grained control over the protected resources

Configuration Overview

To define the configuration for your protected resources you need to create a configuration provider like the following:

See the Configuration section about how to create and register your own configuration provider.

public class CustomConfigurationProvider implements ConfigurationBuilderProvider {

    @Override
    public HTTPConfigurationBuilder getBuilder(ServletContext context) {
        HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder();
        
        // protected resources configuration
        configurationBuilder.protectedResource()

                // unprotected resource. Usually this will be your application's static resources like CSS, JS, etc.
                .resource("/resources/*", ProtectedResourceConstraint.NOT_PROTECTED)

                // the login page is marked as not protected.
                .resource("/login.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // the register page is marked as not protected.
                .resource("/signup.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // the register page is marked as not protected.
                .resource("/signup", ProtectedResourceConstraint.NOT_PROTECTED)

                // the error page is marked as not protected.
                .resource("/error.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // protected all resources. They will be available only for users with a role named 'guest'.
                .resource("/*", "guest");

        return configurationBuilder;
    }

}

By default all your application's resources are protected. But usually you would want to explicit define which of them should be protected (or not) and how. Resources are protected based on three main information:

Security Constraint
Tells which security constraint should be applied for a specific resource, are they: AUTHENTICATION, AUTHORIZATION and NOT_PROTECTED.

URL pattern
Used to map a specific request (and its uri) to a protected resource configuration. If the pattern matches PicketBox will process that request as a protected resource considering its configuration.

Role
Tells which roles are allowed to access a specific resource (or url pattern). Only users with the specified roles would be allowed to access the protected resource.

The example code above demonstrates how you can unprotect some public resources like login, error and signup pages. It also defines that all other resources are allowed only for users with the "guest" role.

This approach is a alternative for the <filter-mapping> configuration giving to you more control over your application's resources.

Understanding the Security Constraints

As said before, security constraints allows you to specify how a resource should be protected. This allows you to:

Define which resources require only authentication. Only authenticated users are allowed to access the configured resource.

Define which resources require both authentication and authorization. Authenticated users are allowed to access the configured resource if the Authorization Manager permits.

Let's say you want to make a resource available only for authenticated users without require authorization:

HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder();

configurationBuilder
    .protectedResource()
        .resource("/privateResource", ProtectedResourceConstraint.AUTHENTICATION)

If you want to allow only authenticated users and also perform authorization you should use:

HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder();

configurationBuilder
    .protectedResource()
        .resource("/privateResource", ProtectedResourceConstraint.AUTHORIZATION)

By default both authentication and authorization is performed when no security constraint is defined.

HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder();

    // protected resources configuration
    configurationBuilder
        .protectedResource()
            .resource("/privateResource", "guest");